Creating Emails in Rulesets

Updated pdexter 2024-03-25

Emails can be triggered from server side rulesets, and can merge data from a document into the target email.

Email Template documents are used to format an email, using document field values and other dynamic values to change the content. Generally, email templates are written as a template for an email about a particular Formbird document template. An email template is invoked from a server side ruleset (PreSaveServer, PostSave, or via a scheduled action) to create emails to send.

Note
The term Email Template should not be confused with the general Formbird document template. Email Templates are documents used to format emails.

Email Template editing

Email Templates can be formulated using the screens below:

Current Listing URL

/form/5657a6985bec6a9d0a93be96

Current Email Template URL

/form/24d7eda0-ce29-11e5-bce0-c145a769f5e9

Email Template fields

Name/Key

Email Templates are referenced by Name/Key. It is important that once an email template is in use, changes to the Name field might break processes that call that email template, unless those processes (eg rulesets) are recoded to call the new name.

To Recipients / CC Recipients

Optional. If the email is to go to fixed recipients, you can add any document here from the system that contains an email field.

It is possible to override these values later in ruleset script with different recipients, using the replacement tokens @to and @cc .

Subject

The subject line to go on the email. This can contain tokens from the corresponding document or to be replaced by script at runtime.

Email Content

The "Email Content" field contains html markup code used to construct the eventual email.

Tokens can be embedded to replace with values from the corresponding document

As of Email Template v202403A, you can now control date formatting directly within the Email Content pane, by including a Moment-like date format in brackets after the token.

Eg {{doc.inceptDate(d MMMM YYYY)}}

Test Tokens

Test tokens are used to define test values for the document field tokens and other tokens, for display of the preview. They are NOT sent in the final email to any recipient. It is a JSON structure, following this syntax:

{
    "doc.fieldA"        : "valueA",
    "doc.fieldB"        : "valueB",
    "doc.systemHeader.createdDate" : "2024-03-25T14:37:37Z",
    ...,
    "tokenX"        : "value-token-X",
    …
}

The test tokens should remain at one level, ie there should not be sub-objects containing further children properties. To simulate such, use a dot delimited string, such as "doc.systemHeader.createdDate" as above.

Dates can be specified in UTC format as shown in the example above.

Send Test Email on Save

(checkbox)

When checked, a test email, using the test tokens, will be sent to the current user.

Using Email Templates in Rulesets

Once an email template is formulated, it can be used from a server-side RuleSet to "draw" an email and send it.

Step 1

In your ruleset script, include the Email Functions includable:

#include "Email Functions JS";

(Requires the "Email Functions JS" RulesetInclude)

Step 2

Call the function launchEmail.

Syntax

object.launchEmail( ntf , emailTemplateName , replacements , function( errMsg ) {
     ...
});

Example

{
#include "JayRule Ruleset Overlay JS",
#include "Email Functions JS",

    ruleset : {
        ...

        // -------------------------------------------------------------------
        // Rule "Water On Alerting"
        // -------------------------------------------------------------------
        ruleWaterOnAlert : {
            ruleCondition : function(ntf) {
                ...
            },

            ruleAction : function(ntf, callback) {
                var ft3 = ntf.scope; 
                ntf.logger.info('Minimum expected water off reached.');

                var emailTemplate = 'Barwon Water On Alert';
                var calcDateM = ft3.moment(ntf.document.completed);
                var calcDateStr = calcDateM.format('DD MMM YYYY, h:mm a');

                var replacements = {
                    'urlRoot'           : ntf.urlRoot,
                    'completedDate'     : calcDateStr
                };

                ft3.emailFunctions.launchEmail(ntf, emailTemplate, replacements, function(errMsg) {
                    if (errMsg) {
                        ntf.logger.info(errMsg);
                    }
                    else {
                        ntf.logger.info('Email sent ok.');

                        ntf.document.waterOnNotificationSentTS = ft3.moment().toISOString();
                    }
                    callback();
                });
            }
        },

        ...
    }
}

Replacements

The replacements argument takes the form of a javascript object that contains key-value pairs which indicate tokens to be replaced in the email template. This is in addition to the {{doc.field}} and {{user.field}} tokens that should automatically be replaced.

var replacements = {
    token-name          : value,
    token-name      : value,
    etc
}

eg

    var replacements = {
        'urlRoot'           : 'https://comp-dev.formbird.com',
        'completedDate'     : '23 Mar 1989'
    };

will replace the following tokens:

{{urlRoot}}
{{completedDate}}

A note on Dates

As of Email Template v202403A, you can now control date formatting directly within the Email Content pane, by including a Moment-like date format in brackets after the token.

Eg

{{doc.inceptDate(d MMMM YYYY)}}

For earlier versions

For earlier versions than above, using automatic tokens for date fields, eg {{doc.inceptDate}} will render an unpalatable representation of the date value, eg '2017-09-13T09:51:33Z'.

For this reason, the replacement structure can be used to set a manually configured token, eg {{inceptDate}}, to a nicely formatted date and/or time string, as in the example

    var inceptDateStr = ft3.moment(ntf.document.inceptDate).format('D MMMM YYYY');

    var replacements = {
        ...,
        'inceptDate'     : inceptDateStr    // '8 January 2016'
    };

Setting Recipients

If it is required to dynamically modify the recipients for the To, CC and BCC of an email template, this can be done through the replacements argument.

Note - this will fully replace any configured recipients from the email template, if used.

Example

    var replacements = {
        'urlRoot'           : 'https://comp-dev.formbird.com',
        'completedDate'     : '23 Mar 1989',
        '@to'               : 'algernon.blackwood@miskatonic.edu',
        '@cc'               : 'tobylong@parel.com.au,mickshort@parel.com.au',
        '@bcc'            : 'scully@xfiles.com'
    };